SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_emacs.idb/usr/freeware/info/emacs-12.z/emacs-12

GNU Info File | 1998-10-28 | 48.5 KB | 1,226 lines

This is Info file ../info/emacs, produced by Makeinfo-1.63 from the
input file emacs.texi.


File: emacs,  Node: Multi-line Indent,  Next: Lisp Indent,  Prev: Basic Indent,  Up: Program Indent

Indenting Several Lines
-----------------------

   When you wish to re-indent several lines of code which have been
altered or moved to a different level in the list structure, you have
several commands available.

`C-M-q'
     Re-indent all the lines within one list (`indent-sexp').

`C-u TAB'
     Shift an entire list rigidly sideways so that its first line is
     properly indented.

`C-M-\'
     Re-indent all lines in the region (`indent-region').

   You can re-indent the contents of a single list by positioning point
before the beginning of it and typing `C-M-q' (`indent-sexp' in Lisp
mode, `indent-c-exp' in C mode; also bound to other suitable commands
in other modes).  The indentation of the line the sexp starts on is not
changed; therefore, only the relative indentation within the list, and
not its position, is changed.  To correct the position as well, type a
TAB before the `C-M-q'.

   If the relative indentation within a list is correct but the
indentation of its first line is not, go to that line and type `C-u
TAB'.  TAB with a numeric argument reindents the current line as usual,
then reindents by the same amount all the lines in the grouping
starting on the current line.  In other words, it reindents the whole
grouping rigidly as a unit.  It is clever, though, and does not alter
lines that start inside strings, or C preprocessor lines when in C mode.

   Another way to specify the range to be re-indented is with the
region.  The command `C-M-\' (`indent-region') applies TAB to every
line whose first character is between point and mark.


File: emacs,  Node: Lisp Indent,  Next: C Indent,  Prev: Multi-line Indent,  Up: Program Indent

Customizing Lisp Indentation
----------------------------

   The indentation pattern for a Lisp expression can depend on the
function called by the expression.  For each Lisp function, you can
choose among several predefined patterns of indentation, or define an
arbitrary one with a Lisp program.

   The standard pattern of indentation is as follows: the second line
of the expression is indented under the first argument, if that is on
the same line as the beginning of the expression; otherwise, the second
line is indented underneath the function name.  Each following line is
indented under the previous line whose nesting depth is the same.

   If the variable `lisp-indent-offset' is non-`nil', it overrides the
usual indentation pattern for the second line of an expression, so that
such lines are always indented `lisp-indent-offset' more columns than
the containing list.

   The standard pattern is overridden for certain functions.  Functions
whose names start with `def' always indent the second line by
`lisp-body-indent' extra columns beyond the open-parenthesis starting
the expression.

   The standard pattern can be overridden in various ways for individual
functions, according to the `lisp-indent-function' property of the
function name.  There are four possibilities for this property:

`nil'
     This is the same as no property; the standard indentation pattern
     is used.

`defun'
     The pattern used for function names that start with `def' is used
     for this function also.

a number, NUMBER
     The first NUMBER arguments of the function are "distinguished"
     arguments; the rest are considered the "body" of the expression.
     A line in the expression is indented according to whether the
     first argument on it is distinguished or not.  If the argument is
     part of the body, the line is indented `lisp-body-indent' more
     columns than the open-parenthesis starting the containing
     expression.  If the argument is distinguished and is either the
     first or second argument, it is indented *twice* that many extra
     columns.  If the argument is distinguished and not the first or
     second argument, the standard pattern is followed for that line.

a symbol, SYMBOL
     SYMBOL should be a function name; that function is called to
     calculate the indentation of a line within this expression.  The
     function receives two arguments:
    STATE
          The value returned by `parse-partial-sexp' (a Lisp primitive
          for indentation and nesting computation) when it parses up to
          the beginning of this line.

    POS
          The position at which the line being indented begins.

     It should return either a number, which is the number of columns of
     indentation for that line, or a list whose car is such a number.
     The difference between returning a number and returning a list is
     that a number says that all following lines at the same nesting
     level should be indented just like this one; a list says that
     following lines might call for different indentations.  This makes
     a difference when the indentation is being computed by `C-M-q'; if
     the value is a number, `C-M-q' need not recalculate indentation
     for the following lines until the end of the list.


File: emacs,  Node: C Indent,  Next: Custom C Indent,  Prev: Lisp Indent,  Up: Program Indent

Commands for C Indentation
--------------------------

   Here are the commands for indentation in C mode and related modes:

`C-c C-q'
     Reindent the current top-level function definition or aggregate
     type declaration (`c-indent-defun').

`C-M-q'
     Reindent each line in the balanced expression that follows point
     (`c-indent-exp').  A prefix argument inhibits error checking and
     warning messages about invalid syntax.

`TAB'
     Reindent the current line, and/or in some cases insert a tab
     character (`c-indent-command').

     If `c-tab-always-indent' is `t', this command always reindents the
     current line and does nothing else.  This is the default.

     If that variable is `nil', this command reindents the current line
     only if point is at the left margin or in the line's indentation;
     otherwise, it inserts a tab.

     Any other value (not `nil' or `t') means always reindent the line,
     and also insert a tab if within a comment, a string, or a
     preprocessor directive.

`C-u TAB'
     Reindent the current line according to its syntax; also rigidly
     reindent any other lines of the expression that starts on the
     current line.  *Note Multi-line Indent::.

   To reindent the whole current buffer, type `C-x h C-M-\'.  This
first selects the whole buffer as the region, then reindents that
region.

   To reindent the current block, use `C-M-u C-M-q'.  This moves to the
front of the block and then reindents it all.


File: emacs,  Node: Custom C Indent,  Prev: C Indent,  Up: Program Indent

Customizing C Indentation
-------------------------

   C mode and related modes use a simple yet flexible mechanism for
customizing indentation.  The mechanism works in two steps: first it
classifies the line syntactically according to its contents and context;
second, it associates each kind of syntactic construct with an
indentation offset which you can customize.

* Menu:

* Syntactic Analysis::
* Indentation Calculation::
* Changing Indent Style::
* Syntactic Symbols::
* Variables for C Indent::
* C Indent Styles::


File: emacs,  Node: Syntactic Analysis,  Next: Indentation Calculation,  Up: Custom C Indent

Step 1--Syntactic Analysis
..........................

   In the first step, the C indentation mechanism looks at the line you
are currently indenting and determines the syntactic components of the
construct on that line.  It builds a list of these syntactic components,
where each component on the list contains a "syntactic symbol" and a
relative buffer position.  Syntactic symbols describe grammatical
elements such as STATEMENT, SUBSTATEMENT, CLASS-OPEN, CLASS-CLOSE,
KNR-ARGDECL, etc.

   Conceptually, a line of C code is always indented relative to the
indentation of some line higher up in the buffer.  This is represented
by the relative buffer positions in the syntactic component list.

   Here is an example.  Suppose we have the following code in a C++ mode
buffer (the line numbers don't actually appear in the buffer):

     1: void swap (int& a, int& b)
     2: {
     3:   int tmp = a;
     4:   a = b;
     5:   b = tmp;
     6: }

   If you type `C-c C-s' (which runs the command
`c-show-syntactic-information') on line 4, it shows the result of the
indentation mechanism for that line:

     ((statement . 32))

   This indicates that the line is a statement and it is indented
relative to buffer position 32, which happens to be the `i' in `int' on
line 3.  If you move the cursor to line 3 and type `C-c C-s', it
displays this:

     ((defun-block-intro . 28))

   This indicates that the `int' line is the first statement in a
block, and is indented relative to buffer position 28, which is the
brace just after the function header.

Here is another example:

     1: int add (int val, int incr, int doit)
     2: {
     3:   if (doit)
     4:     {
     5:       return (val + incr);
     6:     }
     7:   return (val);
     8: }

Typing `C-c C-s' on line 4 displays this:

     ((substatement-open . 43))

   This says that the brace *opens* a substatement block.  By the way,
a "substatement" indicates the line after an `if', `else', `while',
`do', `switch', and `for' statements.

   After a line has been analyzed syntactically for indentation, the
global variable `c-syntactic-context' contains a list that describes
the results.  Each element in this list is a a "syntactic component": a
cons cell containing a syntactic symbol and (optionally) its
corresponding buffer position.  There may be several elements in a
component list; typically only one element has a buffer position.


File: emacs,  Node: Indentation Calculation,  Next: Changing Indent Style,  Prev: Syntactic Analysis,  Up: Custom C Indent

Step 2--Indentation Calculation
...............................

   The C indentation mechanism calculates the indentation for the
current line using the list of syntactic components,
`c-syntactic-context', derived from syntactic analysis.  Each component
is a cons cell that contains a syntactic symbol and may also contain a
pointer to a location in the buffer.

   Each component contributes to the final total indentation of the line
in two ways.  First, the syntactic symbol identifies an element of
`c-offsets-alist', which is an association list mapping syntactic
symbols into indentation offsets.  Each syntactic symbol's offset adds
to the total indentation.  Second, if the component includes a buffer
position, the column number of that position adds to the indentation.
All these offsets and column numbers, added together, give the total
indentation.

   The following examples demonstrate the workings of the C indentation
mechanism:

     1: void swap (int& a, int& b)
     2: {
     3:   int tmp = a;
     4:   a = b;
     5:   b = tmp;
     6: }

   Suppose that point is on line 3 and you type TAB to reindent the
line.  As explained above (*note Syntactic Analysis::.), the syntactic
component list for that line is:

     ((defun-block-intro . 28))

   In this case, the indentation calculation first looks up
`defun-block-intro' in the `c-offsets-alist' alist.  Suppose that it
finds the integer 2; it adds this to the running total (initialized to
zero), yielding a updated total indentation of 2 spaces.

   The next step is to find the column number of buffer position 28.
Since the brace at buffer position 28 is in column zero, this adds 0 to
the running total.  Since this line has only one syntactic component,
the total indentation for the line is 2 spaces.

     1: int add (int val, int incr, int doit)
     2: {
     3:   if (doit)
     4:     {
     5:       return(val + incr);
     6:     }
     7:   return(val);
     8: }

   If you type TAB on line 4, the same process is performed, but with
different data.  The syntactic component list for this line is:

     ((substatement-open . 43))

   Here, the indentation calculation's first job is to look up the
symbol `substatement-open' in `c-offsets-alist'.  Let's assume that the
offset for this symbol is 2.  At this point the running total is 2 (0 +
2 = 2).  Then it adds the column number of buffer position 43, which is
the `i' in `if' on line 3.  This character is in column 2 on that line.
Adding this yields a total indentation of 4 spaces.

   If a syntactic symbol in the analysis of a line does not appear in
`c-offsets-alist', it is ignored; if in addition the variable
`c-strict-syntax-p' is non-`nil', it is an error.


File: emacs,  Node: Changing Indent Style,  Next: Syntactic Symbols,  Prev: Indentation Calculation,  Up: Custom C Indent

Changing Indentation Style
..........................

   There are two ways to customize the indentation style for the C
modes.  First, you can select one of several predefined styles, each of
which specifies offsets for all the syntactic symbols.  For more
flexibility, you can customize the handling of individual syntactic
symbols.  *Note Syntactic Symbols::, for a list of all defined
syntactic symbols.

`M-x c-set-style RET STYLE RET'
     Select predefined indentation style STYLE.  Type `?' when entering
     STYLE to see a list of supported styles; to find out what a style
     looks like, select it and reindent some C code.

`C-c C-o SYMBOL RET OFFSET RET'
     Set the indentation offset for syntactic symbol SYMBOL
     (`c-set-offset').  The second argument OFFSET specifies the new
     indentation offset.

   The `c-offsets-alist' variable controls the amount of indentation to
give to each syntactic symbol.  Its value is an association list, and
each element of the list has the form `(SYNTACTIC-SYMBOL . OFFSET)'.
By changing the offsets for various syntactic symbols, you can
customize indentation in fine detail.

   Each offset value in `c-offsets-alist' can be an integer, a function
or variable name, or one of the following symbols: `+', `-', `++', or
`--', indicating positive or negative multiples of the variable
`c-basic-offset'.  Thus, if you want to change the levels of
indentation to be 3 spaces instead of 2 spaces, set `c-basic-offset' to
3.

   Using a function as the offset value provides the ultimate
flexibility in customizing indentation.  The function is called with a
single argument containing the `cons' of the syntactic symbol and the
relative indent point.  The function should return an integer offset.

   The command `C-c C-o' (`c-set-offset') is the easiest way to set
offsets, both interactively or in your `~/.emacs' file.  First specify
the syntactic symbol, then the offset you want.  *Note Syntactic
Symbols::, for a list of valid syntactic symbols and their meanings.

   The variable `c-offsets-alist-default' holds the default settings
for the offsets of the syntactic symbols.  *Do not change this value!*


File: emacs,  Node: Syntactic Symbols,  Next: Variables for C Indent,  Prev: Changing Indent Style,  Up: Custom C Indent

Syntactic Symbols
.................

   Here is a table of valid syntactic symbols for C mode indentation,
with their syntactic meanings.  Normally, most of these symbols are
assigned offsets in `c-offsets-alist'.

`string'
     Inside a multi-line string.

`c'
     Inside a multi-line C style block comment.

`defun-open'
     On a brace that opens a function definition.

`defun-close'
     On a brace that closes a function definition.

`defun-block-intro'
     In the first line in a top-level defun.

`class-open'
     On a brace that opens a class definition.

`class-close'
     On a brace that closes a class definition.

`inline-open'
     On a brace that opens an in-class inline method.

`inline-close'
     On a brace that closes an in-class inline method.

`ansi-funcdecl-cont'
     In the nether region between an ANSI function declaration and the
     defun opening brace.

`knr-argdecl-intro'
     On the first line of a K&R C argument declaration.

`knr-argdecl'
     In one of the subsequent lines in a K&R C argument declaration.

`topmost-intro'
     On the first line in a topmost construct definition.

`topmost-intro-cont'
     On the topmost definition continuation lines.

`member-init-intro'
     On the first line in a member initialization list.

`member-init-cont'
     On one of the subsequent member initialization list lines.

`inher-intro'
     On the first line of a multiple inheritance list.

`inher-cont'
     On one of the subsequent multiple inheritance lines.

`block-open'
     On a statement block open brace.

`block-close'
     On a statement block close brace.

`brace-list-open'
     On the opening brace of an `enum' or `static' array list.

`brace-list-close'
     On the closing brace of an `enum' or `static' array list.

`brace-list-intro'
     On the first line in an `enum' or `static' array list.

`brace-list-entry'
     On one of the subsequent lines in an `enum' or `static' array list.

`statement'
     On an ordinary statement.

`statement-cont'
     On a continuation line of a statement.

`statement-block-intro'
     On the first line in a new statement block.

`statement-case-intro'
     On the first line in a `case' "block".

`statement-case-open'
     On the first line in a `case' block starting with brace.

`substatement'
     On the first line after an `if', `while', `for', `do', or `else'.

`substatement-open'
     On the brace that opens a substatement block.

`case-label'
     On a `case' or `default' label.

`access-label'
     On a C++ `private', `protected', or `public' access label.

`label'
     On any ordinary label.

`do-while-closure'
     On the `while' that ends a `do'-`while' construct.

`else-clause'
     On the `else' of an `if'-`else' construct.

`comment-intro'
     On a line containing only a comment introduction.

`arglist-intro'
     On the first line in an argument list.

`arglist-cont'
     On one of the subsequent argument list lines when no arguments
     follow on the same line as the the arglist opening parenthesis.

`arglist-cont-nonempty'
     On one of the subsequent argument list lines when at least one
     argument follows on the same line as the arglist opening
     parenthesis.

`arglist-close'
     On the closing parenthesis of an argument list.

`stream-op'
     On one of the lines continuing a stream operator construct.

`inclass'
     On a construct which is nested inside a class definition.

`cpp-macro'
     On the start of a cpp macro.

`friend'
     On a C++ `friend' declaration.

`objc-method-intro'
     On the first line of an Objective-C method definition.

`objc-method-args-cont'
     On one of the lines continuing an Objective-C method definition.

`objc-method-call-cont'
     On one of the lines continuing an Objective-C method call.


File: emacs,  Node: Variables for C Indent,  Next: C Indent Styles,  Prev: Syntactic Symbols,  Up: Custom C Indent

Variables for C Indentation
...........................

   This section describes additional variables which control the
indentation behavior of C mode and related mode.

`c-offsets-alist'
     Association list of syntactic symbols and their indentation
     offsets.  *Note Changing Indent Style::, for details.

`c-offsets-alist-default'
     Default settings for the offsets of the syntactic symbols.  *Note
     Changing Indent Style::.

`c-style-alist'
     Variable for specifying styles of indentation; see below.

`c-basic-offset'
     Amount of basic offset used by `+' and `-' symbols in
     `c-offsets-alist'.

`c-recognize-knr-p'
     If this variable is non-`nil', C mode and Objective C mode
     recognize K&R constructs.  This variable is needed because of
     ambiguities in C syntax that make recognition of K&R constructs
     problematic and slow.  If you always use ANSI C prototype syntax,
     set this variable to `nil' to speed up C indentation.

     This variable is `nil' by default in C++ mode, and `t' by default
     in C mode and Objective C mode.

`c-special-indent-hook'
     Hook for user-defined special indentation adjustments.  This hook
     is called after a line is indented by C mode and related modes.

   The variable `c-style-alist' specifies the predefined indentation
styles.  Each element has form `(NAME VARIABLE-SETTING...)', where NAME
is the name of the style.  Each VARIABLE-SETTING has the form `(VARIABLE
. VALUE)'; VARIABLE is one of the customization variables used by C
mode, and VALUE is the value for that variable when using the selected
style.

   When VARIABLE is `c-offsets-alist', that is a special case: VALUE is
appended to the front of the value of `c-offsets-alist' instead of
replacing that value outright.  Therefore, it is not necessary for
VALUE to specify each and every syntactic symbol--only those for which
the style differs from the default.

   The indentation of lines containing only comments is also affected by
the variable `c-comment-only-line-offset' (*note Comments in C::.).


File: emacs,  Node: C Indent Styles,  Prev: Variables for C Indent,  Up: Custom C Indent

C Indentation Styles
....................

   A "C style" is a collection of indentation style customizations.
Emacs comes with several predefined indentation styles for C code
including `gnu', `k&r', `bsd', `stroustrup' `whitesmith', `ellemtel',
and `cc-mode'.  The default style is `gnu'.

   To choose the style you want, use the command `M-x c-set-style'.
Specify a style name as an argument (case is not significant in C style
names).  The chosen style only affects newly visited buffers, not those
you are already editing.

   To define a new C indentation style, call the function `c-add-style':

     (c-add-style NAME VALUES USE-NOW)

Here NAME is the name of the new style (a string), and VALUES is an
alist whose elements have the form `(VARIABLE . VALUE)'.  The variables
you specify should be among those documented in *Note Variables for C
Indent::.

   If USE-NOW is non-`nil', `c-add-style' switches to the new style
after defining it.


File: emacs,  Node: Matching,  Next: Comments,  Prev: Program Indent,  Up: Programs

Automatic Display Of Matching Parentheses
=========================================

   The Emacs parenthesis-matching feature is designed to show
automatically how parentheses match in the text.  Whenever you type a
self-inserting character that is a closing delimiter, the cursor moves
momentarily to the location of the matching opening delimiter, provided
that is on the screen.  If it is not on the screen, some text near it is
displayed in the echo area.  Either way, you can tell what grouping is
being closed off.

   In Lisp, automatic matching applies only to parentheses.  In C, it
applies to braces and brackets too.  Emacs knows which characters to
regard as matching delimiters based on the syntax table, which is set
by the major mode.  *Note Syntax::.

   If the opening delimiter and closing delimiter are mismatched--such
as in `[x)'--a warning message is displayed in the echo area.  The
correct matches are specified in the syntax table.

   Three variables control parenthesis match display.
`blink-matching-paren' turns the feature on or off; `nil' turns it off,
but the default is `t' to turn match display on.
`blink-matching-delay' says how many seconds to wait; the default is 1,
but on some systems it is useful to specify a fraction of a second.
`blink-matching-paren-distance' specifies how many characters back to
search to find the matching opening delimiter.  If the match is not
found in that far, scanning stops, and nothing is displayed.  This is
to prevent scanning for the matching delimiter from wasting lots of
time when there is no match.  The default is 12,000.

   When using X Windows, you can request a more powerful kind of
automatic parenthesis matching by loading the `paren' library.  To load
it, type `M-x load-library RET paren RET'.  This library turns off the
usual kind of matching parenthesis display and substitutes another:
whenever point is after a close parenthesis, the close parenthesis and
its matching open parenthesis are both highlighted; otherwise, if point
is before an open parenthesis, the matching close parenthesis is
highlighted.  (There is no need to highlight the open parenthesis after
point because the cursor appears on top of that character.)


File: emacs,  Node: Comments,  Next: Balanced Editing,  Prev: Matching,  Up: Programs

Manipulating Comments
=====================

   Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.

* Menu:

* Comment Commands::
* Multi-Line Comments::
* Options for Comments::


File: emacs,  Node: Comment Commands,  Next: Multi-Line Comments,  Up: Comments

Comment Commands
----------------

   The comment commands insert, kill and align comments.

`M-;'
     Insert or align comment (`indent-for-comment').

`C-x ;'
     Set comment column (`set-comment-column').

`C-u - C-x ;'
     Kill comment on current line (`kill-comment').

`M-LFD'
     Like RET followed by inserting and aligning a comment
     (`indent-new-comment-line').

`M-x comment-region'
     Add or remove comment delimiters on all the lines in the region.

   The command that creates a comment is `M-;' (`indent-for-comment').
If there is no comment already on the line, a new comment is created,
aligned at a specific column called the "comment column".  The comment
is created by inserting the string Emacs thinks comments should start
with (the value of `comment-start'; see below).  Point is left after
that string.  If the text of the line extends past the comment column,
then the indentation is done to a suitable boundary (usually, at least
one space is inserted).  If the major mode has specified a string to
terminate comments, that is inserted after point, to keep the syntax
valid.

   `M-;' can also be used to align an existing comment.  If a line
already contains the string that starts comments, then `M-;' just moves
point after it and re-indents it to the conventional place.  Exception:
comments starting in column 0 are not moved.

   Some major modes have special rules for indenting certain kinds of
comments in certain contexts.  For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
instead of at the comment column.  Comments which start with three
semicolons are supposed to start at the left margin.  Emacs understands
these conventions by indenting a double-semicolon comment using TAB,
and by not changing the indentation of a triple-semicolon comment at
all.

     ;; This function is just an example
     ;;; Here either two or three semicolons are appropriate.
     (defun foo (x)
     ;;; And now, the first part of the function:
       ;; The following line adds one.
       (1+ x))           ; This line adds one.

   In C code, a comment preceded on its line by nothing but whitespace
is indented like a line of code.

   Even when an existing comment is properly aligned, `M-;' is still
useful for moving directly to the start of the comment.

   `C-u - C-x ;' (`kill-comment') kills the comment on the current line,
if there is one.  The indentation before the start of the comment is
killed as well.  If there does not appear to be a comment in the line,
nothing is done.  To reinsert the comment on another line, move to the
end of that line, do `C-y', and then do `M-;' to realign it.  Note that
`C-u - C-x ;' is not a distinct key; it is `C-x ;'
(`set-comment-column') with a negative argument.  That command is
programmed so that when it receives a negative argument it calls
`kill-comment'.  However, `kill-comment' is a valid command which you
could bind directly to a key if you wanted to.


File: emacs,  Node: Multi-Line Comments,  Next: Options for Comments,  Prev: Comment Commands,  Up: Comments

Multiple Lines of Comments
--------------------------

   If you are typing a comment and wish to continue it on another line,
you can use the command `M-LFD' (`indent-new-comment-line').  This
terminates the comment you are typing, creates a new blank line
afterward, and begins a new comment indented under the old one.  When
Auto Fill mode is on, going past the fill column while typing a comment
causes the comment to be continued in just this fashion.  If point is
not at the end of the line when `M-LFD' is typed, the text on the rest
of the line becomes part of the new comment line.

   To turn existing lines into comment lines, use the `M-x
comment-region' command.  It adds comment delimiters to the lines that
start in the region, thus commenting them out.  With a negative
argument, it does the opposite--it deletes comment delimiters from the
lines in the region.

   With a positive argument, `comment-region' duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert.  Thus, in Lisp mode, `C-u 2
M-x comment-region' adds `;;' to each line.  Duplicating the comment
delimiter is a way of calling attention to the comment.  It can also
affect how the comment is indented.  In Lisp, for proper indentation,
you should use an argument of two, if between defuns, and three, if
within a defun.


File: emacs,  Node: Options for Comments,  Prev: Multi-Line Comments,  Up: Comments

Options Controlling Comments
----------------------------

   The comment column is stored in the variable `comment-column'.  You
can set it to a number explicitly.  Alternatively, the command `C-x ;'
(`set-comment-column') sets the comment column to the column point is
at.  `C-u C-x ;' sets the comment column to match the last comment
before point in the buffer, and then does a `M-;' to align the current
line's comment under the previous one.  Note that `C-u - C-x ;' runs
the function `kill-comment' as described above.

   The variable `comment-column' is per-buffer: setting the variable in
the normal fashion affects only the current buffer, but there is a
default value which you can change with `setq-default'.  *Note
Locals::.  Many major modes initialize this variable for the current
buffer.

   The comment commands recognize comments based on the regular
expression that is the value of the variable `comment-start-skip'.
Make sure this regexp does not match the null string.  It may match more
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is `"/\\*+ *"', which
matches extra stars and spaces after the `/*' itself.  (Note that `\\'
is needed in Lisp syntax to include a `\' in the string, which is
needed to deny the first star its special meaning in regexp syntax.
*Note Regexps::.)

   When a comment command makes a new comment, it inserts the value of
`comment-start' to begin it.  The value of `comment-end' is inserted
after point, so that it will follow the text that you will insert into
the comment.  In C mode, `comment-start' has the value `"/* "' and
`comment-end' has the value `" */"'.

   The variable `comment-multi-line' controls how `M-LFD'
(`indent-new-comment-line') behaves when used inside a comment.  If
`comment-multi-line' is `nil', as it normally is, then the comment on
the starting line is terminated and a new comment is started on the new
following line.  If `comment-multi-line' is not `nil', then the new
following line is set up as part of the same comment that was found on
the starting line.  This is done by not inserting a terminator on the
old line, and not inserting a starter on the new line.  In languages
where multi-line comments work, the choice of value for this variable
is a matter of taste.

   The variable `comment-indent-function' should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by
various major modes.  The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted.  It should return the column in which the
comment ought to start.  For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.


File: emacs,  Node: Balanced Editing,  Next: Symbol Completion,  Prev: Comments,  Up: Programs

Editing Without Unbalanced Parentheses
======================================

`M-('
     Put parentheses around next sexp(s) (`insert-parentheses').

`M-)'
     Move past next close parenthesis and re-indent
     (`move-over-close-and-reindent').

   The commands `M-(' (`insert-parentheses') and `M-)'
(`move-over-close-and-reindent') are designed to facilitate a style of
editing which keeps parentheses balanced at all times.  `M-(' inserts a
pair of parentheses, either together as in `()', or, if given an
argument, around the next several sexps.  It leaves point after the
open parenthesis.  The command `M-)' moves past the close parenthesis,
deleting any indentation preceding it (in this example there is none),
and indenting with LFD after it.

   For example, instead of typing `( F O O )', you can type `M-( F O
O', which has the same effect except for leaving the cursor before the
close parenthesis.

   `M-(' may insert a space before the open parenthesis, depending on
the syntax class of the preceding character.  Set
`parens-dont-require-spaces' to a non-`nil' value if you wish to
inhibit this.


File: emacs,  Node: Symbol Completion,  Next: Documentation,  Prev: Balanced Editing,  Up: Programs

Completion for Symbol Names
===========================

   Usually completion happens in the minibuffer.  But one kind of
completion is available in all buffers: completion for symbol names.

   The character `M-TAB' runs a command to complete the partial symbol
before point against the set of meaningful symbol names.  Any
additional characters determined by the partial name are inserted at
point.

   If the partial name in the buffer has more than one possible
completion and they have no additional characters in common, a list of
all possible completions is displayed in another window.

   There are two ways of determining the set of legitimate symbol names
to complete against.  In most major modes, this uses a tags table
(*note Tags::.); the legitimate symbol names are the tag names listed in
the tags table file.  The command which implements this is
`complete-tag'.

   In Emacs-Lisp mode, the name space for completion normally consists
of nontrivial symbols present in Emacs--those that have function
definitions, values or properties.  However, if there is an
open-parenthesis immediately before the beginning of the partial symbol,
only symbols with function definitions are considered as completions.
The command which implements this is `lisp-complete-symbol'.

   In Text mode and related modes, `M-TAB' completes words based on the
spell-checker's dictionary.  *Note Spelling::.


File: emacs,  Node: Documentation,  Next: Change Log,  Prev: Symbol Completion,  Up: Programs

Documentation Commands
======================

   As you edit Lisp code to be run in Emacs, the commands `C-h f'
(`describe-function') and `C-h v' (`describe-variable') can be used to
print documentation of functions and variables that you want to call.
These commands use the minibuffer to read the name of a function or
variable to document, and display the documentation in a window.

   For extra convenience, these commands provide default arguments
based on the code in the neighborhood of point.  `C-h f' sets the
default to the function called in the innermost list containing point.
`C-h v' uses the symbol name around or adjacent to point as its default.

   Documentation on operating system commands, library functions and
system calls can be obtained with the `M-x manual-entry' command.  This
reads a topic as an argument, and displays the "man page" on that
topic.  `manual-entry' starts a background process that formats the
manual page, by running the `man' program.  The result goes in a buffer
named `*man TOPIC*'.  These buffers use a special major mode, Man mode,
that facilitates scrolling and examining other manual pages.  For
details, type `C-h m' while in a man page buffer.

   For a long man page, setting the faces properly can take substantial
time.  By default, Emacs uses faces in man pages if you are using X
Windows.  You can turn off use of faces in man pages by setting the
variable `Man-fontify-manpage-flag' to `nil'.

   If you insert the text of a man page into an Emacs buffer in some
other fashion, you can use the command `M-x Man-fontify-manpage' to
perform the same conversions that `M-x manual-entry' does.

   Eventually the GNU project hopes to replace most man pages with
better-organized manuals that you can browse with Info.  *Note Misc
Help::.  Since this process is only partially completed, it is still
useful to read manual pages.


File: emacs,  Node: Change Log,  Next: Tags,  Prev: Documentation,  Up: Programs

Change Logs
===========

   The Emacs command `C-x 4 a' adds a new entry to the change log file
for the file you are editing (`add-change-log-entry-other-window').

   A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes.  Normally it is kept in a file called `ChangeLog'
in the same directory as the file you are editing, or one of its parent
directories.  A single `ChangeLog' file can record changes for all the
files in its directory and all its subdirectories.

   A change log entry starts with a header line that contains your name,
your email address (taken from the variable `user-mail-address'), and
the current date and time.  Aside from these header lines, every line
in the change log starts with a space or a tab.  The bulk of the entry
consists of "items", each of which starts with a line starting with
whitespace and a star.  Here are two entries, each with two items:

     Wed May  5 14:11:45 1993  Richard Stallman  <[e-mail]>

             * man.el: Rename symbols `man-*' to `Man-*'.
             (manual-entry): Make prompt string clearer.

             * simple.el (blink-matching-paren-distance):
             Change default to 12,000.

     Tue May  4 12:42:19 1993  Richard Stallman  <[e-mail]>

             * vc.el (minor-mode-map-alist): Don't use it if it's void.
             (vc-cancel-version): Doc fix.

   One entry can describe several changes; each change should have its
own item.  Normally there should be a blank line between items.  When
items are related (parts of the same change, in different places), group
them by leaving no blank line between them.  The second entry above
contains two items grouped in this way.

   `C-x 4 a' visits the change log file and creates a new entry unless
the most recent entry is for today's date and your name.  It also
creates a new item for the current file.  For many languages, it can
even guess the name of the function or other object that was changed.

   The change log file is visited in Change Log mode.  In this major
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.  LFD
and auto-fill indent each new line like the previous line; this is
convenient for entering the contents of an entry.

   Version control systems are another way to keep track of changes in
your program and keep a change log.  *Note Log Entries::.


File: emacs,  Node: Tags,  Next: Emerge,  Prev: Change Log,  Up: Programs

Tags Tables
===========

   A "tags table" is a description of how a multi-file program is
broken up into files.  It lists the names of the component files and the
names and positions of the functions (or other named subunits) in each
file.  Grouping the related files makes it possible to search or replace
through all the files with one command.  Recording the function names
and positions makes possible the `M-.'  command which finds the
definition of a function by looking up which of the files it is in.

   Tags tables are stored in files called "tags table files".  The
conventional name for a tags table file is `TAGS'.

   Each entry in the tags table records the name of one tag, the name
of the file that the tag is defined in (implicitly), and the position
in that file of the tag's definition.

   Just what names from the described files are recorded in the tags
table depends on the programming language of the described file.  They
normally include all functions and subroutines, and may also include
global variables, data types, and anything else convenient.  Each name
recorded is called a "tag".

* Menu:

* Tag Syntax::        Tag syntax for various types of code and text files.
* Create Tags Table::    Creating a tags table with `etags'.
* Select Tags Table::    How to visit a tags table.
* Find Tag::        Commands to find the definition of a specific tag.
* Tags Search::        Using a tags table for searching and replacing.
* List Tags::        Listing and finding tags defined in a file.


File: emacs,  Node: Tag Syntax,  Next: Create Tags Table,  Up: Tags

Source File Tag Syntax
----------------------

   * In Lisp code, any function defined with `defun', any variable
     defined with `defvar' or `defconst', and in general the first
     argument of any expression that starts with `(def' in column zero,
     is a tag.

   * In Scheme code, tags include anything defined with `def' or with a
     construct whose name starts with `def'.  They also include
     variables set with `set!' at top level in the file.

   * In C code, any C function or typedef is a tag, and so are
     definitions of struct, union and enum.  Any `#define' is also a
     tag, unless `--no-defines' is specified when the tags table is
     constructed, which sometimes makes the tags file much smaller.  In
     C++ code, member functions are also recognized.

   * In Yacc or Bison input files, each rule defines as a tag the
     nonterminal it constructs.  The portions of the file that contain
     C code are parsed as C code.

   * In Fortran code, functions and subroutines are tags.

   * In Pascal code, the tags are the functions and procedures defined
     in the file.

   * In Perl code, the tags are the procedures defined by the `sub'
     keyword.

   * In Prolog code, a tag name appears at the left margin.

   * In Erlang code, the tags are the functions, records, and macros
     defined in the file.

   * In assembler code, labels appearing at the beginning of a line,
     followed by a colon, are tags.

   * In LaTeX text, the argument of any of the commands `\chapter',
     `\section', `\subsection', `\subsubsection', `\eqno', `\label',
     `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
     `\index', is a tag.

     Other commands can make tags as well, if you specify them in the
     environment variable `TEXTAGS' before invoking `etags'.  The value
     of this environment variable should be a colon-separated list of
     commands names.  For example,

          TEXTAGS="def:newcommand:newenvironment"
          export TEXTAGS

     specifies (using Bourne shell syntax) that the commands `\def',
     `\newcommand' and `\newenvironment' also define tags.

   * You can also generate tags based on regexp matching (*note Create
     Tags Table::.) for any text file.


File: emacs,  Node: Create Tags Table,  Next: Select Tags Table,  Prev: Tag Syntax,  Up: Tags

Creating Tags Tables
--------------------

   The `etags' program is used to create a tags table file.  It knows
the syntax of several languages, as described in *Note Tag Syntax::.
Here is how to run `etags':

     etags INPUTFILES...

The `etags' program reads the specified files, and writes a tags table
named `TAGS' in the current working directory.  `etags' recognizes the
language used in an input file based on its file name and contents.
You can specify the language with the `--language=NAME' option,
described below.

   If the tags table data become outdated due to changes in the files
described in the table, the way to update the tags table is the same
way it was made in the first place.  It is not necessary to do this
often.

   If the tags table fails to record a tag, or records it for the wrong
file, then Emacs cannot possibly find its definition.  However, if the
position recorded in the tags table becomes a little bit wrong (due to
some editing in the file that the tag definition is in), the only
consequence is a slight delay in finding the tag.  Even if the stored
position is very wrong, Emacs will still find the tag, but it must
search the entire file for it.

   So you should update a tags table when you define new tags that you
want to have listed, or when you move tag definitions from one file to
another, or when changes become substantial.  Normally there is no need
to update the tags table after each edit, or even every day.

   One tags table can effectively include another.  Specify the included
tags file name with the `--include=FILE' option when creating the file
that is to include it.  The latter file then acts as if it contained
all the files specified in the included file, as well as the files it
directly contains.

   If you specify the source files with relative file names when you run
`etags', the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
files.

   If you specify absolute file names as arguments to `etags', then the
tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
`/', or with `DEVICE:/' on MS-DOS and Windows.

   When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some systems
have a limit on its length.  The simplest way to circumvent this limit
is to tell `etags' to read the file names from its standard input, by
typing a dash in place of the file names, like this:

     find . -name "*.[chCH]" -print | etags -

   Use the option `--language=NAME' to specify the language explicitly.
You can intermix these options with file names; each one applies to
the file names that follow it.  Specify `--language=auto' to tell
`etags' to resume guessing the language from the file names and file
contents.  Specify `--language=none' to turn off language-specific
processing entirely; then `etags' recognizes tags by regexp matching
alone.  `etags --help' prints the list of the languages `etags' knows,
and the file name rules for guessing the language.

   The `--regex' option provides a general way of recognizing tags
based on regexp matching.  You can freely intermix it with file names.
Each `--regex' option adds to the preceding ones, and applies only to
the following files.  The syntax is:

     --regex=/TAGREGEXP[/NAMEREGEXP]/

where TAGREGEXP is used to match the lines to tag.  It is always
anchored, that is, it behaves as if preceded by `^'.  If you want to
account for indentation, just match any initial number of blanks by
beginning your regular expression with `[ \t]*'.  In the regular
expressions, `\' quotes the next character, and `\t' stands for the tab
character.  Note that `etags' does not handle the other C escape
sequences for special characters.

   You should not match more characters with TAGREGEXP than that needed
to recognize what you want to tag.  If the match is such that more
characters than needed are unavoidably matched by TAGREGEXP, you may
find useful to add a NAMEREGEXP, in order to narrow the tag scope.  You
can find some examples below.

   The `-R' option deletes all the regexps defined with `--regex'
options.  It applies to the file names following it, as you can see
from the following example:

     etags --regex=/REG1/ voo.doo --regex=/REG2/ \
         bar.ber -R --lang=lisp los.er

Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
according to their contents.  `etags' also uses REG1 to recognize
additional tags in `voo.doo', and both REG1 and REG2 to recognize
additional tags in `bar.ber'.  `etags' uses the Lisp tags rules, and no
regexp matching, to recognize tags in `los.er'.

   Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

Tag the `DEFVAR' macros in the emacs source files:

     --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'

Tag VHDL files (this example is a single long line, broken here for
formatting reasons):

     --language=none
     --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
     --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
     \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'

Tag Cobol files (every label starting in column seven):

     --language=none --regex='/.......[a-zA-Z0-9-]+\./'

Tag Postscript files (every label starting in column one):

     --language=none --regex='#/[^ \t{]+#/'

Tag TCL files (this last example shows the usage of a NAMEREGEXP):

     --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

   For a list of the other available `etags' options, execute `etags
--help'.